home *** CD-ROM | disk | FTP | other *** search
/ Games of Daze / Infomagic - Games of Daze (Summer 1995) (Disc 1 of 2).iso / x2ftp / msdos / libs / mthr25 / readme.txt < prev   
Text File  |  1995-03-29  |  7KB  |  156 lines
  1. README.TXT for MicroThread V2.5
  2.  
  3. What is MicroThread?
  4.  
  5. MicroThread is a minimal Turbo C multi-threading library for DOS 
  6. programs. Normal DOS programs are normally single-threaded, i.e. a 
  7. single determinate path of execution. However, in certain situations, 
  8. programs can be much easier to design if there can have multiple 
  9. concurrent paths of execution, i.e. multi-threaded. MicroThread 
  10. allows your Borland C DOS programs to have this multi-threading 
  11. capability, simply and easily.
  12.  
  13. MicroThread consists of a pre-emptive scheduling kernel which 
  14. dispatch threads on every timer interrupt(INT 8). It has a priority-
  15. based scheduling algorithm, and  has support for semaphores, critical 
  16. sections and inter-thread messages. The main features of MicroThread 
  17. are:
  18.  
  19. 1) It is written entirely in Turbo C, with no assembly code, so that 
  20. it can be easily understood and modified to suit your needs.
  21.  
  22. 2) It is small. Unlike a number of other such libraries, MicroThread 
  23. contains only the basic essential code to implement a multi-threading 
  24. kernel for DOS programs and very little else. (Unfortunately the code 
  25. has grown a bit with each version, but I will try to keep this down 
  26. to a minimum).
  27.  
  28. 3) It is FREE. I have placed the source code in the public domain in 
  29. the hope that somebody else would find it useful.
  30.  
  31.  
  32. What MicroThread isn't:
  33.  
  34. 1) MicroThread isn't a replacement for a "industrial-strength" multi-
  35. tasking or multi-threading kernel. It was written primarily as an aid 
  36. for teaching multi-threading on an operating-systems course at the 
  37. University of Wolverhampton, UK. 
  38.  
  39. 2) It is not in any way optimised, either in its algorithms, 
  40. functionality, or speed. The code source was written in such a way 
  41. that it would be easier to go through on an overhead projection 
  42. screen in front of a class, rather than for elegance, style or speed. 
  43. Thus, the verbosity of the code and comments may be a bit of an over-
  44. kill at times.
  45.  
  46.  
  47. What do you need?
  48.  
  49. Though MicroThread was written mainly with Borland C V3.1, the source 
  50. files should compile quite happy under most versions of Turbo/Borland 
  51. C/C++. They have been compiled with the following versions: Turbo C 
  52. V2.0, Turbo C++ V1.1, Borland C V3.1 and Borland C++ V4.5.
  53.  
  54. The main MicroThread kernel is contained within the file MTHREAD.C 
  55. and you will also need the header file MTHREAD.H. The file MTCRTLIB.C 
  56. contains some C runtime library functions. Unfortunately Turbo C's 
  57. runtime library functions were never designed for multi-threaded use, 
  58. and are not re-entrant. Thus, you can't use them in a multi-threaded 
  59. program, except if you guard against re-entering them from different 
  60. threads at the same time. MTCRTLIB.C contains several functions which 
  61. uses a semaphore to guard against re-entrancy problems in calls to 
  62. Turbo C runtime function. The range of functions in MTCRTLIB.C are by 
  63. no means complete, as they were the only ones I had need to date, but 
  64. it should be straight forward enough add your own functions. It 
  65. however, you have no need for the runtime library functions or are 
  66. using runtime library functions in only one thread at any time, then 
  67. you won't need MTCRTLIB.C
  68.  
  69. Several example programs (DEMO1.C, DEMO2.C,...) are included within 
  70. the distribution along with their project files(DEMO1.PRJ,etc.). The 
  71. problem with project files is that they are version and installation 
  72. specific. These particular ones are specific to my version(V3.1) and 
  73. installation (C:\BORLANDC), so you may have to adjust the various 
  74. options once you have loaded them.
  75.  
  76. When you are building an application with MicroThread, there are 
  77. several points to bear in mind:
  78.  
  79. 1) MicroThread has only ever been tested with the large model. I 
  80. haven't tried it with any other models yet as I very rarely use them 
  81. (I haven't installed them to save on disk space)
  82.  
  83. 2) MicroThread needs a stack frame. It uses different stacks to keep 
  84. track of different threads. Thus you must build your application with 
  85. the "Standard Stack Frame" option enabled. You mustn't however enable 
  86. the stack overflow testing option. This will kill MicroThread stone-
  87. cold dead.
  88.  
  89. 3) DOS is not re-entrant. So if you use any DOS functions or any C 
  90. runtime functions which eventually calls DOS routines, MicroThread 
  91. will stop multi-threading temporarily until the DOS routine returns. 
  92. It accomplishes this by testing the InDOS flag. The upshot of this is 
  93. that if you use Control-S or the PAUSE key to pause the screen 
  94. output, you will effectively pause all threads in your program.
  95.  
  96. 4) MicroThread will NOT run inside the Turbo C IDE debugger. The 
  97. Turbo C IDE debugger get confused by MicroThread's stack switching 
  98. and will crash. One possible way to trace through a MicroThread 
  99. program is to use Turbo Debugger and trace through it at the 
  100. instruction level(assembly code trace). Breakpoints, and 
  101. stepping(rather than tracing) also don't work terribly well.
  102.  
  103. 5) Floating point isn't supported at the moment. Turbo C's floating 
  104. point emulator library isn't re-entrant, but can be guarded in the 
  105. same way as the other runtime libraries. However, if you have a 
  106. coprocessor or 486DX, then I am afraid things are not so great. 
  107. Adding support for coprocessors will mean delving into assembly code, 
  108. which confuses the issue would make MicroThread less of a useful 
  109. teaching tool for me. One possible work-around is to limit floating 
  110. point operations to only one thread, but this won't always work if 
  111. the other thread are also using other C runtime functions. Oh well, 
  112. such is life.
  113.  
  114.  
  115. More details
  116.  
  117. Details of how to use MicroThread are contained with the file 
  118. MTHREAD.TXT. The file describes the various functions and macros that 
  119. your application can call to use MicroThread.
  120.  
  121.  
  122. Disclaimer
  123.  
  124. Please do not hold me responsible if any of your programs break when 
  125. you use MicroThread. The only thing I will guarantee is that 
  126. MicroThread's behaviour is totally unpredictable, and will definitely 
  127. crash, at some point. When it does crash, it will probably also take 
  128. out whatever multi-tasking environment you happen to be running at 
  129. the time, be it DR Concurrent DOS, Windows 3.1, Windows 95, OS/2 
  130. Warp, Windows NT, or Desqview. You have been warn
  131.  
  132.  
  133. Use and Distribution
  134.  
  135. Please feel free to use and distribute the source code in any manner 
  136. that you feel fit. If you do distribute your MicroThreaded 
  137. applications, I would appreciate a mention. If you develop any 
  138. extensions or modifications to MicroThread or demonstration programs 
  139. that you want to distribute, I would be grateful if you drop me a 
  140. note, so that I can mention it in this 'readme' file.
  141.  
  142.  
  143.  
  144. Comments and suggestions would be very welcome to :
  145.  
  146.       Internet Email : i.h.ting@wlv.ac.uk
  147.       Compuserve     : 100023,3363
  148.  
  149.       Otherwise      : I H Ting
  150.                        University of Wolverhampton
  151.                        School of Computing & I. T.
  152.                        Wulfruna Street
  153.                        WOLVERHAMPTON WV1 1SB
  154.                        UK.
  155.  
  156.